<!DOCTYPE html>

<html>

<head>

<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta http-equiv="X-UA-Compatible" content="IE=EDGE" />

<meta name="viewport" content="width=device-width, initial-scale=1" />



<title>Installing packages</title>

<script>// Pandoc 2.9 adds attributes on both header and div. We remove the former (to
// be compatible with the behavior of Pandoc < 2.8).
document.addEventListener('DOMContentLoaded', function(e) {
  var hs = document.querySelectorAll("div.section[class*='level'] > :first-child");
  var i, h, a;
  for (i = 0; i < hs.length; i++) {
    h = hs[i];
    if (!/^h[1-6]$/i.test(h.tagName)) continue;  // it should be a header h1-h6
    a = h.attributes;
    while (a.length > 0) h.removeAttribute(a[0].name);
  }
});
</script>

<style type="text/css">
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
</style>



<style type="text/css">
code {
white-space: pre;
}
.sourceCode {
overflow: visible;
}
</style>
<style type="text/css" data-origin="pandoc">
html { -webkit-text-size-adjust: 100%; }
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } 
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.at { color: #7d9029; } 
code span.bn { color: #40a070; } 
code span.bu { color: #008000; } 
code span.cf { color: #007020; font-weight: bold; } 
code span.ch { color: #4070a0; } 
code span.cn { color: #880000; } 
code span.co { color: #60a0b0; font-style: italic; } 
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.do { color: #ba2121; font-style: italic; } 
code span.dt { color: #902000; } 
code span.dv { color: #40a070; } 
code span.er { color: #ff0000; font-weight: bold; } 
code span.ex { } 
code span.fl { color: #40a070; } 
code span.fu { color: #06287e; } 
code span.im { color: #008000; font-weight: bold; } 
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.kw { color: #007020; font-weight: bold; } 
code span.op { color: #666666; } 
code span.ot { color: #007020; } 
code span.pp { color: #bc7a00; } 
code span.sc { color: #4070a0; } 
code span.ss { color: #bb6688; } 
code span.st { color: #4070a0; } 
code span.va { color: #19177c; } 
code span.vs { color: #4070a0; } 
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } 
</style>
<script>
// apply pandoc div.sourceCode style to pre.sourceCode instead
(function() {
  var sheets = document.styleSheets;
  for (var i = 0; i < sheets.length; i++) {
    if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue;
    try { var rules = sheets[i].cssRules; } catch (e) { continue; }
    var j = 0;
    while (j < rules.length) {
      var rule = rules[j];
      // check if there is a div.sourceCode rule
      if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") {
        j++;
        continue;
      }
      var style = rule.style.cssText;
      // check if color or background-color is set
      if (rule.style.color === '' && rule.style.backgroundColor === '') {
        j++;
        continue;
      }
      // replace div.sourceCode by a pre.sourceCode rule
      sheets[i].deleteRule(j);
      sheets[i].insertRule('pre.sourceCode{' + style + '}', j);
    }
  }
})();
</script>




<style type="text/css">body {
background-color: #fff;
margin: 1em auto;
max-width: 700px;
overflow: visible;
padding-left: 2em;
padding-right: 2em;
font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
font-size: 14px;
line-height: 1.35;
}
#TOC {
clear: both;
margin: 0 0 10px 10px;
padding: 4px;
width: 400px;
border: 1px solid #CCCCCC;
border-radius: 5px;
background-color: #f6f6f6;
font-size: 13px;
line-height: 1.3;
}
#TOC .toctitle {
font-weight: bold;
font-size: 15px;
margin-left: 5px;
}
#TOC ul {
padding-left: 40px;
margin-left: -1.5em;
margin-top: 5px;
margin-bottom: 5px;
}
#TOC ul ul {
margin-left: -2em;
}
#TOC li {
line-height: 16px;
}
table {
margin: 1em auto;
border-width: 1px;
border-color: #DDDDDD;
border-style: outset;
border-collapse: collapse;
}
table th {
border-width: 2px;
padding: 5px;
border-style: inset;
}
table td {
border-width: 1px;
border-style: inset;
line-height: 18px;
padding: 5px 5px;
}
table, table th, table td {
border-left-style: none;
border-right-style: none;
}
table thead, table tr.even {
background-color: #f7f7f7;
}
p {
margin: 0.5em 0;
}
blockquote {
background-color: #f6f6f6;
padding: 0.25em 0.75em;
}
hr {
border-style: solid;
border: none;
border-top: 1px solid #777;
margin: 28px 0;
}
dl {
margin-left: 0;
}
dl dd {
margin-bottom: 13px;
margin-left: 13px;
}
dl dt {
font-weight: bold;
}
ul {
margin-top: 0;
}
ul li {
list-style: circle outside;
}
ul ul {
margin-bottom: 0;
}
pre, code {
background-color: #f7f7f7;
border-radius: 3px;
color: #333;
white-space: pre-wrap; 
}
pre {
border-radius: 3px;
margin: 5px 0px 10px 0px;
padding: 10px;
}
pre:not([class]) {
background-color: #f7f7f7;
}
code {
font-family: Consolas, Monaco, 'Courier New', monospace;
font-size: 85%;
}
p > code, li > code {
padding: 2px 0px;
}
div.figure {
text-align: center;
}
img {
background-color: #FFFFFF;
padding: 2px;
border: 1px solid #DDDDDD;
border-radius: 3px;
border: 1px solid #CCCCCC;
margin: 0 5px;
}
h1 {
margin-top: 0;
font-size: 35px;
line-height: 40px;
}
h2 {
border-bottom: 4px solid #f7f7f7;
padding-top: 10px;
padding-bottom: 2px;
font-size: 145%;
}
h3 {
border-bottom: 2px solid #f7f7f7;
padding-top: 10px;
font-size: 120%;
}
h4 {
border-bottom: 1px solid #f7f7f7;
margin-left: 8px;
font-size: 105%;
}
h5, h6 {
border-bottom: 1px solid #ccc;
font-size: 105%;
}
a {
color: #0033dd;
text-decoration: none;
}
a:hover {
color: #6666ff; }
a:visited {
color: #800080; }
a:visited:hover {
color: #BB00BB; }
a[href^="http:"] {
text-decoration: underline; }
a[href^="https:"] {
text-decoration: underline; }

code > span.kw { color: #555; font-weight: bold; } 
code > span.dt { color: #902000; } 
code > span.dv { color: #40a070; } 
code > span.bn { color: #d14; } 
code > span.fl { color: #d14; } 
code > span.ch { color: #d14; } 
code > span.st { color: #d14; } 
code > span.co { color: #888888; font-style: italic; } 
code > span.ot { color: #007020; } 
code > span.al { color: #ff0000; font-weight: bold; } 
code > span.fu { color: #900; font-weight: bold; } 
code > span.er { color: #a61717; background-color: #e3d2d2; } 
</style>




</head>

<body>




<h1 class="title toc-ignore">Installing packages</h1>



<div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1" tabindex="-1"></a><span class="fu">library</span>(renv)</span>
<span id="cb1-2"><a href="#cb1-2" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb1-3"><a href="#cb1-3" tabindex="-1"></a><span class="co">#&gt; Attaching package: &#39;renv&#39;</span></span>
<span id="cb1-4"><a href="#cb1-4" tabindex="-1"></a><span class="co">#&gt; The following objects are masked from &#39;package:stats&#39;:</span></span>
<span id="cb1-5"><a href="#cb1-5" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb1-6"><a href="#cb1-6" tabindex="-1"></a><span class="co">#&gt;     embed, update</span></span>
<span id="cb1-7"><a href="#cb1-7" tabindex="-1"></a><span class="co">#&gt; The following objects are masked from &#39;package:utils&#39;:</span></span>
<span id="cb1-8"><a href="#cb1-8" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb1-9"><a href="#cb1-9" tabindex="-1"></a><span class="co">#&gt;     history, upgrade</span></span>
<span id="cb1-10"><a href="#cb1-10" tabindex="-1"></a><span class="co">#&gt; The following objects are masked from &#39;package:base&#39;:</span></span>
<span id="cb1-11"><a href="#cb1-11" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb1-12"><a href="#cb1-12" tabindex="-1"></a><span class="co">#&gt;     autoload, load, remove, use</span></span></code></pre></div>
<p>Package installation is an important part of renv. This vignette
gives you the details, starting with an overview of renv’s cache, before
going into various installation challenges around building from source
and downloading with proxies or authentication.</p>
<div id="cache" class="section level2">
<h2>Cache</h2>
<p>One of renv’s primary features is the global package cache, which
shared across all projects. The renv package cache provides two primary
benefits:</p>
<ol style="list-style-type: decimal">
<li><p>Installing and restoring packages is much faster, as renv can
find and re-use previously installed packages from the cache.</p></li>
<li><p>Projects take up less disk space, because each project doesn’t
need to contain it’s own copy of every package.</p></li>
</ol>
<p>When installing a package, renv installs into the global cache and
then adds a symlink<a href="#fn1" class="footnote-ref" id="fnref1"><sup>1</sup></a> to that directory in the project library.
That way each renv project remains isolated from other projects on your
system, but they can still re-use the same installed packages.</p>
<p>The process by which packages enter the cache is roughly as
follows:</p>
<ol style="list-style-type: decimal">
<li><p>Package installation is requested via
e.g. <code>install.packages()</code>, or <code>renv::install()</code>,
or as part of <code>renv::restore()</code>.</p></li>
<li><p>If renv is able to find the requested version of the package in
the cache, then that package is linked into the project library, and
installation is complete.</p></li>
<li><p>Otherwise, the package is downloaded and installed into the
project library.</p></li>
<li><p>After installation of the package has successfully completed, the
package is then copied into the global package cache, and then symlinked
into the project library.</p></li>
</ol>
<p>In some cases, renv will be unable to directly link from the global
package cache to your project library, e.g. if the package cache and
your project library live on different disk volumes. In such a case,
renv will instead copy the package from the cache into the project
library. This is much slower, so is worth avoiding.</p>
<div id="cache-location" class="section level3">
<h3>Cache location</h3>
<p>You can find the location of the current cache with
<code>renv::paths$cache()</code>. By default, it will be in one of the
following folders:</p>
<ul>
<li>Linux: <code>~/.cache/R/renv/cache</code></li>
<li>macOS:
<code>~/Library/Caches/org.R-project.R/R/renv/cache</code></li>
<li>Windows: <code>%LOCALAPPDATA%/renv/cache</code></li>
</ul>
<p>If you’d like to share the package cache across multiple users, you
can do so by setting the <code>RENV_PATHS_CACHE</code> environment
variable to a shared path. This variable should be set in an R startup
file to make it apply to all R sessions. While you can set it in a
project-local <code>.Renviron</code>, or the user-level
<code>~/.Renviron</code>, we generally recommend using the R
installation’s site-wide <code>Renviron.site</code> if you’d like to
ensure the same cache path is visible to all users of R on a system.</p>
<p>You may also want to set <code>RENV_PATHS_CACHE</code> so that the
global package cache can be stored on the same volume as the projects
you normally work on. This is especially important when working projects
stored on a networked filesystem.</p>
</div>
<div id="multiple-caches" class="section level3">
<h3>Multiple caches</h3>
<p>It is also possible to configure renv to use multiple cache
locations. For example, you might want to make both a user-local package
cache, as well as a global administrator-managed cache, visible within
an renv project. To do so, you can specify the paths to the cache
separated with a <code>;</code> (or <code>:</code> on Unix if
preferred). For example:</p>
<pre><code>RENV_PATHS_CACHE=/path/to/local/cache;/path/to/global/cache</code></pre>
<p>In such a case, renv will iterate over the cache locations in order
when trying to find a package, and newly-installed packages will enter
the first writable cache path listed in
<code>RENV_PATHS_CACHE</code>.</p>
</div>
<div id="shared-cache-locations" class="section level3">
<h3>Shared cache locations</h3>
<p>When the renv cache is enabled, if that cache is shared and visible
to multiple users, then each of those users will have an opportunity to
install packages into the renv cache. However, some care must be taken
to ensure that these packages can be used by different users in your
environment:</p>
<ol style="list-style-type: decimal">
<li><p>Packages copied into the cache may have <a href="https://en.wikipedia.org/wiki/Access-control_list">Access-control
Lists</a> (ACLs), which might prevent others from using packages that
have been installed into the cache. If this is the case, it’s important
that ACLs be set (or updated) on cache entries so that the cache is
accessible to each user requiring access. When deploying renv in an
enterprise environment, the system administrator should take care to
ensure ACLs (if any) allow users access to packages within the renv
cache.</p></li>
<li><p>By default, packages copied into the cache will remain “owned” by
the user that requested installation of that package. If you’d like renv
to instead re-assign ownership of the cached package to a separate user
account, you can set the <code>RENV_CACHE_USER</code> environment
variable. When set, renv will attempt to run
<code>chown -R &lt;package&gt; &lt;user&gt;</code> to update cache
ownership after the package has been copied into the cache.</p></li>
</ol>
</div>
<div id="caveats" class="section level3">
<h3>Caveats</h3>
<p>While we recommend enabling the cache by default, if you’re having
trouble with it, you can disable it by setting the project setting
<code>renv::settings$use.cache(FALSE)</code>. Doing this will ensure
that packages are then installed into your project library directly,
without attempting to link and use packages from the renv cache.</p>
<p>If you find a problematic package has entered the cache (for example,
an installed package has become corrupted), that package can be removed
with the <code>renv::purge()</code> function. See the
<code>?purge</code> documentation for caveats and things to be aware of
when removing packages from the cache.</p>
<p>You can also force a package to be re-installed and re-cached with
the following functions:</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb3-1"><a href="#cb3-1" tabindex="-1"></a><span class="co"># restore packages from the lockfile, bypassing the cache</span></span>
<span id="cb3-2"><a href="#cb3-2" tabindex="-1"></a>renv<span class="sc">::</span><span class="fu">restore</span>(<span class="at">rebuild =</span> <span class="cn">TRUE</span>)</span>
<span id="cb3-3"><a href="#cb3-3" tabindex="-1"></a></span>
<span id="cb3-4"><a href="#cb3-4" tabindex="-1"></a><span class="co"># re-install a package</span></span>
<span id="cb3-5"><a href="#cb3-5" tabindex="-1"></a>renv<span class="sc">::</span><span class="fu">install</span>(<span class="st">&quot;&lt;package&gt;&quot;</span>, <span class="at">rebuild =</span> <span class="cn">TRUE</span>)</span>
<span id="cb3-6"><a href="#cb3-6" tabindex="-1"></a></span>
<span id="cb3-7"><a href="#cb3-7" tabindex="-1"></a><span class="co"># rebuild all packages in the project</span></span>
<span id="cb3-8"><a href="#cb3-8" tabindex="-1"></a>renv<span class="sc">::</span><span class="fu">rebuild</span>()</span></code></pre></div>
<p>See each function’s respective documentation for more details.</p>
</div>
</div>
<div id="building-from-source" class="section level2">
<h2>Building from source</h2>
<p>Where possible, renv will install package binaries, but sometimes a
binary is not available and you have to build from source. Installation
from source can be challenging for a few reasons:</p>
<ol style="list-style-type: decimal">
<li><p>Your system will need to have a compatible compiler toolchain
available. In some cases, R packages may depend on C / C++ features that
aren’t available in an older system toolchain, especially in some older
Linux enterprise environments.</p></li>
<li><p>Your system will need requisite system libraries, as many R
packages contain compiled C / C++ code that depend on and link to these
packages.</p></li>
</ol>
<!-- TODO: renv::equip() for Linux + macOS; use sysreqsdb -->
<div id="configure-flags" class="section level3">
<h3>Configure flags</h3>
<p>Many <code>R</code> packages have a <code>configure</code> script
that needs to be run to prepare the package for installation. Arguments
and environment variables can be passed through to those scripts in a
manner similar to <code>install.packages()</code>. In particular, the
<code>R</code> options <code>configure.args</code> and
<code>configure.vars</code> can be used to map package names to their
appropriate configuration. For example:</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb4-1"><a href="#cb4-1" tabindex="-1"></a><span class="co"># installation of RNetCDF may require us to set include paths for netcdf</span></span>
<span id="cb4-2"><a href="#cb4-2" tabindex="-1"></a>configure.args <span class="ot">=</span> <span class="fu">c</span>(<span class="at">RNetCDF =</span> <span class="st">&quot;--with-netcdf-include=/usr/include/udunits2&quot;</span>)</span>
<span id="cb4-3"><a href="#cb4-3" tabindex="-1"></a><span class="fu">options</span>(<span class="at">configure.args =</span> configure.args)</span>
<span id="cb4-4"><a href="#cb4-4" tabindex="-1"></a>renv<span class="sc">::</span><span class="fu">install</span>(<span class="st">&quot;RNetCDF&quot;</span>)</span></code></pre></div>
<p>This could also be specified as, for example,</p>
<div class="sourceCode" id="cb5"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb5-1"><a href="#cb5-1" tabindex="-1"></a><span class="fu">options</span>(</span>
<span id="cb5-2"><a href="#cb5-2" tabindex="-1"></a>  <span class="at">configure.args.RNetCDF =</span> <span class="st">&quot;--with-netcdf-include=/usr/include/udunits2&quot;</span></span>
<span id="cb5-3"><a href="#cb5-3" tabindex="-1"></a>)</span>
<span id="cb5-4"><a href="#cb5-4" tabindex="-1"></a>renv<span class="sc">::</span><span class="fu">install</span>(<span class="st">&quot;RNetCDF&quot;</span>)</span></code></pre></div>
</div>
<div id="install-flags" class="section level3">
<h3>Install flags</h3>
<p>Similarly, additional flags that should be passed to
<code>R CMD INSTALL</code> can be set via the <code>install.opts</code>
<code>R</code> option:</p>
<div class="sourceCode" id="cb6"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb6-1"><a href="#cb6-1" tabindex="-1"></a><span class="co"># installation of R packages using the Windows Subsystem for Linux</span></span>
<span id="cb6-2"><a href="#cb6-2" tabindex="-1"></a><span class="co"># may require the `--no-lock` flag to be set during install</span></span>
<span id="cb6-3"><a href="#cb6-3" tabindex="-1"></a><span class="fu">options</span>(<span class="at">install.opts =</span> <span class="st">&quot;--no-lock&quot;</span>)</span>
<span id="cb6-4"><a href="#cb6-4" tabindex="-1"></a>renv<span class="sc">::</span><span class="fu">install</span>(<span class="st">&quot;xml2&quot;</span>)</span>
<span id="cb6-5"><a href="#cb6-5" tabindex="-1"></a></span>
<span id="cb6-6"><a href="#cb6-6" tabindex="-1"></a><span class="co"># alternatively, you can set such options for specific packages with e.g.</span></span>
<span id="cb6-7"><a href="#cb6-7" tabindex="-1"></a><span class="fu">options</span>(<span class="at">install.opts =</span> <span class="fu">list</span>(<span class="at">xml2 =</span> <span class="st">&quot;--no-lock&quot;</span>))</span>
<span id="cb6-8"><a href="#cb6-8" tabindex="-1"></a>renv<span class="sc">::</span><span class="fu">install</span>(<span class="st">&quot;xml2&quot;</span>)</span></code></pre></div>
</div>
<div id="vignettes" class="section level3">
<h3>Vignettes</h3>
<p>renv does not build vignettes when installing a package from source.
This is because vignettes often require suggested packages, and
installing all suggested packages (particularly from source) can be
arduous.</p>
<p>If you want to distribute vignettes for your own packages, we suggest
creating your own repository of binaries, either with <a href="https://r-universe.dev/">R Universe</a> (for publicly hosted
packages on GitHub), with <a href="https://posit.co/products/enterprise/package-manager/">Posit
Package Manager</a>, or with <a href="https://eddelbuettel.github.io/drat/">drat</a>.</p>
</div>
</div>
<div id="downloads" class="section level2">
<h2>Downloads</h2>
<p>By default, renv uses <a href="https://curl.se/">curl</a> for file
downloads when available. This allows renv to support a number of
download features across multiple versions of R, including:</p>
<ul>
<li>Custom headers (used especially for authentication),</li>
<li>Connection timeouts,</li>
<li>Download retries on transient errors.</li>
</ul>
<p>If <code>curl</code> is not available on your machine, it is highly
recommended that you install it. Newer versions of Windows 10 come with
a bundled version of <code>curl.exe</code>; other users on Windows can
use <code>renv::equip()</code> to download and install a recent copy of
<code>curl</code>. Newer versions of macOS come with a bundled version
of <code>curl</code> that is adequate for usage with renv, and most
Linux package managers have a modern version of <code>curl</code>
available in their package repositories. You can also configure which
<code>curl</code> executable is used by setting the
<code>RENV_CURL_EXECUTABLE</code> environment variable, if
necessary.</p>
<p><code>curl</code> downloads can be configured through renv’s
configuration settings – see <code>?renv::config</code> for more
details.</p>
<div id="alternative-downloaders" class="section level3">
<h3>Alternative downloaders</h3>
<p>If you’ve already configured R’s downloader and would like to bypass
renv’s attempts to use <code>curl</code>, you can use the R option
<code>renv.download.override</code>. For example, executing:</p>
<div class="sourceCode" id="cb7"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb7-1"><a href="#cb7-1" tabindex="-1"></a><span class="fu">options</span>(<span class="at">renv.download.override =</span> utils<span class="sc">::</span>download.file)</span></code></pre></div>
<p>would instruct renv to use R’s own download machinery when attempting
to download files from the internet (respecting the R options
<code>download.file.method</code> and <code>download.file.extra</code>
as appropriate). Advanced users can also provide their own download
function, provided its signature matches that of
<code>utils::download.file()</code>.</p>
<p>You can also instruct renv to use a different download method by
setting the <code>RENV_DOWNLOAD_METHOD</code> environment variable. For
example:</p>
<pre><code># use Windows&#39; internal download machinery
Sys.setenv(RENV_DOWNLOAD_METHOD = &quot;wininet&quot;)

# use R&#39;s bundled libcurl implementation
Sys.setenv(RENV_DOWNLOAD_METHOD = &quot;libcurl&quot;)</code></pre>
<p>If you find that downloads work outside of renv projects, but not
within renv projects, you may need to tell renv to use the same download
file method that R has been configured to use. You can check which
download method R is currently configured to use with:</p>
<div class="sourceCode" id="cb9"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb9-1"><a href="#cb9-1" tabindex="-1"></a><span class="fu">getOption</span>(<span class="st">&quot;download.file.method&quot;</span>)</span></code></pre></div>
<p>And the downloader currently used by renv can be queried with:</p>
<div class="sourceCode" id="cb10"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb10-1"><a href="#cb10-1" tabindex="-1"></a>renv<span class="sc">:::</span><span class="fu">renv_download_method</span>()</span></code></pre></div>
<p>You can force renv to use the same download method as R by
setting:</p>
<div class="sourceCode" id="cb11"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb11-1"><a href="#cb11-1" tabindex="-1"></a><span class="fu">Sys.setenv</span>(<span class="at">RENV_DOWNLOAD_METHOD =</span> <span class="fu">getOption</span>(<span class="st">&quot;download.file.method&quot;</span>))</span></code></pre></div>
<p>and, if necessary, you could also set this environment variable
within e.g. your <code>~/.Renviron</code>, so that it is visible to all
R sessions. See <code>?Startup</code> for more details.</p>
<p>Note that other features (e.g. authentication) may not be supported
when using an alternative download file method – you will have to
configure the downloader yourself if that is required. See
<code>?download.file</code> for more details.</p>
</div>
<div id="proxies" class="section level3">
<h3>Proxies</h3>
<p>If your downloads need to go through a proxy server, then there are a
variety of approaches you can take to make this work:</p>
<ol style="list-style-type: decimal">
<li><p>Set the <code>http_proxy</code> and / or <code>https_proxy</code>
environment variables. These environment variables can contain the full
URL to your proxy server, including a username + password if
necessary.</p></li>
<li><p>You can use a <code>.curlrc</code> (<code>_curlrc</code> on
Windows) to provide information about the proxy server to be used. This
file should be placed in your home folder (see
<code>Sys.getenv(&quot;HOME&quot;)</code>, or <code>Sys.getenv(&quot;R_USER&quot;)</code> on
Windows); alternatively, you can set the <code>CURL_HOME</code>
environment variable to point to a custom ‘home’ folder to be used by
<code>curl</code> when resolving the runtime configuration file. On
Windows, you can also place your <code>_curlrc</code> in the same
directory where the <code>curl.exe</code> binary is located.</p></li>
</ol>
<p>See the curl documentation on <a href="https://ec.haxx.se/usingcurl/proxies/">proxies</a> and <a href="https://ec.haxx.se/cmdline/configfile.html">config files</a> for
more details.</p>
<p>As an <a href="https://github.com/rstudio/renv/issues/146">example</a>, the
following <code>_curlrc</code> works when using authentication with NTLM
and SSPI on Windows:</p>
<pre><code>--proxy &quot;your.proxy.dns:port&quot;
--proxy-ntlm
--proxy-user &quot;:&quot;
--insecure</code></pre>
<p>The <a href="https://cran.r-project.org/package=curl">curl</a> R
package also has a helper:</p>
<pre><code>curl::ie_get_proxy_for_url()</code></pre>
<p>which may be useful when attempting to discover this proxy
address.</p>
</div>
<div id="authentication" class="section level3">
<h3>Authentication</h3>
<p>Your project may make use of packages which are available from remote
sources requiring some form of authentication to access – for example, a
GitHub enterprise server. Usually, either a personal access token (PAT)
or username + password combination is required for authentication. renv
is able to authenticate when downloading from such sources, using the
same system as the <a href="https://cran.r-project.org/package=remotes">remotes</a> package.
In particular, environment variables are used to record and transfer the
required authentication information.</p>
<table>
<thead>
<tr class="header">
<th><strong>Remote Source</strong></th>
<th><strong>Authentication</strong></th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>GitHub</td>
<td><code>GITHUB_PAT</code></td>
</tr>
<tr class="even">
<td>GitLab</td>
<td><code>GITLAB_PAT</code></td>
</tr>
<tr class="odd">
<td>Bitbucket</td>
<td><code>BITBUCKET_USER</code> + <code>BITBUCKET_PASSWORD</code></td>
</tr>
<tr class="even">
<td>Git Remotes</td>
<td><code>GIT_PAT</code> / <code>GIT_USER</code> +
<code>GIT_PASSWORD</code></td>
</tr>
</tbody>
</table>
<p>These credentials can be stored in e.g. <code>.Renviron</code>, or
can be set in your R session through other means as appropriate.</p>
<p>If you require custom authentication for different packages (for
example, your project makes use of packages available on different
GitHub enterprise servers), you can use the <code>renv.auth</code> R
option to provide package-specific authentication settings.
<code>renv.auth</code> can either be a a named list associating package
names with environment variables, or a function accepting a package name
+ record, and returning a list of environment variables. For
example:</p>
<div class="sourceCode" id="cb14"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb14-1"><a href="#cb14-1" tabindex="-1"></a><span class="co"># define a function providing authentication</span></span>
<span id="cb14-2"><a href="#cb14-2" tabindex="-1"></a><span class="fu">options</span>(<span class="at">renv.auth =</span> <span class="cf">function</span>(package, record) {</span>
<span id="cb14-3"><a href="#cb14-3" tabindex="-1"></a>  <span class="cf">if</span> (package <span class="sc">==</span> <span class="st">&quot;MyPackage&quot;</span>)</span>
<span id="cb14-4"><a href="#cb14-4" tabindex="-1"></a>    <span class="fu">return</span>(<span class="fu">list</span>(<span class="at">GITHUB_PAT =</span> <span class="st">&quot;&lt;pat&gt;&quot;</span>))</span>
<span id="cb14-5"><a href="#cb14-5" tabindex="-1"></a>})</span>
<span id="cb14-6"><a href="#cb14-6" tabindex="-1"></a></span>
<span id="cb14-7"><a href="#cb14-7" tabindex="-1"></a><span class="co"># use a named list directly</span></span>
<span id="cb14-8"><a href="#cb14-8" tabindex="-1"></a><span class="fu">options</span>(<span class="at">renv.auth =</span> <span class="fu">list</span>(</span>
<span id="cb14-9"><a href="#cb14-9" tabindex="-1"></a>  <span class="at">MyPackage =</span> <span class="fu">list</span>(<span class="at">GITHUB_PAT =</span> <span class="st">&quot;&lt;pat&gt;&quot;</span>)</span>
<span id="cb14-10"><a href="#cb14-10" tabindex="-1"></a>))</span>
<span id="cb14-11"><a href="#cb14-11" tabindex="-1"></a></span>
<span id="cb14-12"><a href="#cb14-12" tabindex="-1"></a><span class="co"># alternatively, set package-specific option</span></span>
<span id="cb14-13"><a href="#cb14-13" tabindex="-1"></a><span class="co"># as a list</span></span>
<span id="cb14-14"><a href="#cb14-14" tabindex="-1"></a><span class="fu">options</span>(<span class="at">renv.auth.MyPackage =</span> <span class="fu">list</span>(<span class="at">GITHUB_PAT =</span> <span class="st">&quot;&lt;pat&gt;&quot;</span>))</span>
<span id="cb14-15"><a href="#cb14-15" tabindex="-1"></a><span class="co"># as a function</span></span>
<span id="cb14-16"><a href="#cb14-16" tabindex="-1"></a><span class="fu">options</span>(<span class="at">renv.auth.MyPackage =</span> <span class="cf">function</span>(record) {</span>
<span id="cb14-17"><a href="#cb14-17" tabindex="-1"></a>   <span class="fu">list</span>(<span class="at">GITHUB_PAT =</span> <span class="st">&quot;&lt;pat&gt;&quot;</span>)</span>
<span id="cb14-18"><a href="#cb14-18" tabindex="-1"></a>})</span></code></pre></div>
<p>For packages installed from Git remotes, renv will attempt to use
<code>git</code> from the command line to download and restore the
associated package. Hence, it is recommended that authentication is done
through SSH keys when possible.</p>
<p>Authentication may be required when resolving a package from a remote
specification. If the package name cannot be inferred directly from the
remote, it can be supplied with a prefix of the form
<code>&lt;package&gt;=</code>. For example, the igraph package on GitHub
at <a href="https://github.com/igraph/rigraph" class="uri">https://github.com/igraph/rigraph</a> could be installed
with:</p>
<pre><code>renv::install(&quot;igraph=igraph/rigraph&quot;)</code></pre>
<div id="azure-devops" class="section level4">
<h4>Azure DevOps</h4>
<p>Authentication with Azure DevOps may require credentials to be set in
a slightly different way. In particular, you can use:</p>
<pre><code>GITHUB_USER = &lt;username&gt;
GITHUB_PASS = &lt;password&gt;</code></pre>
<p>replacing <code>&lt;username&gt;</code> and
<code>&lt;password&gt;</code> as appropriate – for example, your
password may just be a PAT. See <a href="https://github.com/rstudio/renv/issues/1751" class="uri">https://github.com/rstudio/renv/issues/1751</a> for more
details.</p>
</div>
<div id="git-and-personal-access-tokens" class="section level4">
<h4>Git and Personal Access Tokens</h4>
<p>Rather than username + password, some remote Git repositories might
require Personal Access Tokens (PATs) for authentication. Typically,
such servers expect authentication credentials where:</p>
<ul>
<li>Your PAT is supplied as the username,</li>
<li>Either an empty response, or the string <code>x-oauth-basic</code>,
is provided as the password.</li>
</ul>
<p>To help facilitate this, you can set:</p>
<pre><code>GIT_USER = &lt;pat&gt;
GIT_PASS = x-oauth-basic</code></pre>
<p>in an appropriate startup R file.</p>
</div>
</div>
<div id="custom-headers" class="section level3">
<h3>Custom headers</h3>
<p>If you want to set arbitrary headers when downloading files using
renv, you can do so using the <code>renv.download.headers</code> R
option. It should be a function that accepts a URL, and returns a named
character vector indicating the headers which should be supplied when
accessing that URL.</p>
<p>For example, suppose you have a package repository hosted at
<code>https://my/repository</code>, and the credentials required to
access that repository are stored in the <code>AUTH_HEADER</code>
environment variable. You could define
<code>renv.download.headers</code> like so:</p>
<div class="sourceCode" id="cb18"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb18-1"><a href="#cb18-1" tabindex="-1"></a><span class="fu">options</span>(<span class="at">renv.download.headers =</span> <span class="cf">function</span>(url) {</span>
<span id="cb18-2"><a href="#cb18-2" tabindex="-1"></a>  <span class="cf">if</span> (<span class="fu">grepl</span>(<span class="st">&quot;^https://my/repository&quot;</span>, url))</span>
<span id="cb18-3"><a href="#cb18-3" tabindex="-1"></a>    <span class="fu">return</span>(<span class="fu">c</span>(<span class="at">Authorization =</span> <span class="fu">Sys.getenv</span>(<span class="st">&quot;AUTH_HEADER&quot;</span>)))</span>
<span id="cb18-4"><a href="#cb18-4" tabindex="-1"></a>})</span></code></pre></div>
<p>With the above, renv will set the <code>Authorization</code> header
whenever it attempts to download files from the repository at URL
<code>https://my/repository</code>.</p>
</div>
<div id="debugging" class="section level3">
<h3>Debugging</h3>
<p>If having problems with downloads, you can get more debugging
information (including raw requests and responses) by setting:</p>
<div class="sourceCode" id="cb19"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb19-1"><a href="#cb19-1" tabindex="-1"></a><span class="fu">options</span>(<span class="at">renv.download.trace =</span> <span class="cn">TRUE</span>) </span></code></pre></div>
</div>
</div>
<div class="footnotes footnotes-end-of-document">
<hr />
<ol>
<li id="fn1"><p>Or junction points, on Windows. Junction points are
unfortunately not supported on Windows network shares; see <a href="https://learn.microsoft.com/en-us/windows/win32/fileio/hard-links-and-junctions">Hard
links and junctions</a> for more details.<a href="#fnref1" class="footnote-back">↩︎</a></p></li>
</ol>
</div>



<!-- code folding -->


<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
  (function () {
    var script = document.createElement("script");
    script.type = "text/javascript";
    script.src  = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
    document.getElementsByTagName("head")[0].appendChild(script);
  })();
</script>

</body>
</html>
